<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>fmtmsg</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_005_134">&nbsp;</a>NAME</h4><blockquote>
fmtmsg - display a message in the specified format on standard
error and/or a system console
</blockquote><h4><a name = "tag_000_005_135">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="fmtmsg.h.html">fmtmsg.h</a>&gt;

int fmtmsg(long <i>classification</i>, const char *<i>label</i>, int <i>severity</i>,
    const char *<i>text</i>, const char *<i>action</i>, const char *<i>tag</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_136">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>fmtmsg()</i>
function can be used to display messages in a specified format instead of the
traditional
<i><a href="printf.html">printf()</a></i>
function.
<p>
Based on a message's classification component,
<i>fmtmsg()</i>
writes a formatted message either to standard error, to the console, or to both.
<p>
A formatted message consists of up to five components as defined below.  The
component <i>classification</i> is not part of a message displayed to the user,
but defines the source of the message and directs the display of the formatted
message.
<dl compact>

<dt><i>classification</i><dd>Contains identifiers from the following groups of major classifications and
subclassifications.  Any one identifier from a subclass may be used in
combination with a single identifier from a different subclass.  Two or more
identifiers from the same subclass should not be used together, with the
exception of identifiers from the display subclass.  (Both display subclass
identifiers may be used so that messages can be displayed to both standard
error and the system console).
<dl compact>

<dt><b>Major Classifications</b><dd>
Identifies the source of the condition.
Identifiers are: MM_HARD (hardware),
MM_SOFT (software), and MM_FIRM (firmware).

<dt><b>Message Source Subclassifications</b><dd>
Identifies the type of software in which the problem is detected.
Identifiers are: MM_APPL (application), MM_UTIL (utility),
and MM_OPSYS (operating system).

<dt><b>Display Subclassifications</b><dd>
Indicates where the message is to be displayed.  Identifiers are: MM_PRINT to
display the message on the standard error stream, MM_CONSOLE to display the
message on the system console.  One or both identifiers may be used.

<dt><b>Status Subclassifications</b><dd>
Indicates whether the application will recover from the condition.
Identifiers are: MM_RECOVER (recoverable) and MM_NRECOV (non-recoverable).

</dl>
<p>
An additional identifier, MM_NULLMC, indicates that no classification
component is supplied for the message.
<p>
<dt><i>label</i><dd>Identifies the source of the message.  The format is two fields separated by a
colon. The first field is up to 10 bytes, the second is up to 14 bytes.
<p>
<dt><i>severity</i><dd>Indicates the seriousness of the condition.  Identifiers for the levels of
<i>severity</i> are:
<dl compact>

<dt>MM_HALT<dd>
Indicates that the application has encountered a severe fault and is halting.
Produces the string "HALT".

<dt>MM_ERROR<dd>
Indicates that the application has detected a fault.
Produces the string "ERROR".

<dt>MM_WARNING<dd>
Indicates a condition that is out of the ordinary,
that might be a problem, and should be watched.
Produces the string "WARNING".

<dt>MM_INFO<dd>
Provides information about a condition that is not in error.
Produces the string "INFO".

<dt>MM_NOSEV<dd>
Indicates that no severity level is supplied for the message.

</dl>
<p>
<dt><i>text</i><dd>Describes the error condition that produced the message.  The character string
is not limited to a specific size.  If the character string is empty, then the
text produced is unspecified.
<p>
<dt><i>action</i><dd>Describes the first step to be taken in the
error-recovery process.  The
<i>fmtmsg()</i>
function precedes the action string with the prefix: "TO FIX:".
The <i>action</i> string is not limited to a specific size.
<p>
<dt><i>tag</i><dd>An identifier that references on-line documentation for the message.
Suggested usage is that <i>tag</i> includes the <i>label</i> and a unique
identifying number.  A sample <i>tag</i> is "XSI:cat:146".
<p>
</dl>
<p>
The
<i>MSGVERB</i>
environment variable (for message verbosity) tells
<i>fmtmsg()</i>
which message components it is to select when writing messages to standard
error.  The value of
<i>MSGVERB</i>
is a colon-separated list of optional keywords.  Valid <i>keywords</i> are:
label, severity, text, action, and
tag.  If
<i>MSGVERB</i>
contains a keyword for a component and the component's value is not
the component's null value,
<i>fmtmsg()</i>
includes that component in the message when writing the message to standard
error.  If
<i>MSGVERB</i>
does not include a keyword for a message component, that component is not
included in the display of the message.  The keywords may appear in any
order.  If
<i>MSGVERB</i>
is not defined, if its value is the null string, if its value is not of the
correct format, or if it contains keywords other than the valid ones listed
above,
<i>fmtmsg()</i>
selects all components.
<p>
<i>MSGVERB</i>
affects only which components are selected for display to standard
error.  All message components are included in console messages.
</blockquote><h4><a name = "tag_000_005_137">&nbsp;</a>RETURN VALUE</h4><blockquote>
The
<i>fmtmsg()</i>
function returns one of the following values:
<dl compact>

<dt>MM_OK<dd>
The function succeeded.

<dt>MM_NOTOK<dd>
The function failed completely.

<dt>MM_NOMSG<dd>
The function was unable to generate a message on standard error,
but otherwise succeeded.

<dt>MM_NOCON<dd>
The function was unable to generate a console message,
but otherwise succeeded.

</dl>
</blockquote><h4><a name = "tag_000_005_138">&nbsp;</a>ERRORS</h4><blockquote>
None.
<br>
</blockquote><h4><a name = "tag_000_005_139">&nbsp;</a>EXAMPLES</h4><blockquote>
Example 1:
<p>
The following example of
<i>fmtmsg()</i>:
<pre>
<code>
fmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option",
"refer to cat in user's reference manual", "XSI:cat:001")
</code>
</pre>
<p>
produces a complete message in the specified message format:
<pre>
<code>
XSI:cat: ERROR: illegal option
TO FIX: refer to cat in user's reference manual XSI:cat:001
</code>
</pre>
<p>
Example 2:
<p>
When the environment variable
<i>MSGVERB</i>
is set as follows:
<pre>
<code>
MSGVERB=severity:text:action
</code>
</pre>
<p>
and the Example 1 is used,
<i>fmtmsg()</i>
produces:
<pre>
<code>
ERROR: illegal option
TO FIX: refer to cat in user's reference manual
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_140">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
One or more message components may be systematically omitted from messages
generated by an application by using the null value of the argument for that
component.
</blockquote><h4><a name = "tag_000_005_141">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_142">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="printf.html">printf()</a></i>,
<i><a href="fmtmsg.h.html">&lt;fmtmsg.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
